home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_time.h.z / apr_time.h
C/C++ Source or Header  |  2002-07-08  |  9KB  |  257 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_TIME_H
  56. #define APR_TIME_H
  57.  
  58. #include "apr.h"
  59. #include "apr_pools.h"
  60. #include "apr_errno.h"
  61.  
  62. #ifdef __cplusplus
  63. extern "C" {
  64. #endif /* __cplusplus */
  65. /**
  66.  * @file apr_time.h
  67.  * @brief APR Time Library
  68.  */
  69. /**
  70.  * @defgroup APR_Time Time Routines
  71.  * @ingroup APR
  72.  * @{
  73.  */
  74. /** month names */
  75. APR_DECLARE_DATA extern const char apr_month_snames[12][4];
  76. /** day names */
  77. APR_DECLARE_DATA extern const char apr_day_snames[7][4];
  78.  
  79.  
  80. /** number of microseconds since 00:00:00 january 1, 1970 UTC */
  81. typedef apr_int64_t apr_time_t;
  82.  
  83.  
  84. /** mechanism to properly type apr_time_t literals */
  85. #define APR_TIME_C(val) APR_INT64_C(val)
  86.  
  87. /** mechanism to properly print apr_time_t values */
  88. #define APR_TIME_T_FMT APR_INT64_T_FMT
  89.  
  90. /** intervals for I/O timeouts, in microseconds */
  91. typedef apr_int64_t apr_interval_time_t;
  92. /** short interval for I/O timeouts, in microseconds */
  93. typedef apr_int32_t apr_short_interval_time_t;
  94.  
  95. /** number of microseconds per second */
  96. #define APR_USEC_PER_SEC APR_TIME_C(1000000)
  97.  
  98. #define apr_time_usec(time) ((apr_int32_t)(time) % APR_USEC_PER_SEC)
  99.  
  100. #define apr_time_sec(time) ((apr_int64_t)(time) / APR_USEC_PER_SEC)
  101.  
  102. #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC)
  103.  
  104. #define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \
  105.                                 + (apr_time_t)(usec))
  106.  
  107. /**
  108.  * return the current time
  109.  */
  110. APR_DECLARE(apr_time_t) apr_time_now(void);
  111.  
  112. /**
  113.  * a structure similar to ANSI struct tm with the following differences:
  114.  *  - tm_usec isn't an ANSI field
  115.  *  - tm_gmtoff isn't an ANSI field (it's a bsdism)
  116.  */
  117. typedef struct apr_time_exp_t apr_time_exp_t;
  118.  
  119. struct apr_time_exp_t {
  120.     /** microseconds past tm_sec */
  121.     apr_int32_t tm_usec;
  122.     /** (0-61) seconds past tm_min */
  123.     apr_int32_t tm_sec;
  124.     /** (0-59) minutes past tm_hour */
  125.     apr_int32_t tm_min;
  126.     /** (0-23) hours past midnight */
  127.     apr_int32_t tm_hour;
  128.     /** (1-31) day of the month */
  129.     apr_int32_t tm_mday;
  130.     /** (0-11) month of the year */
  131.     apr_int32_t tm_mon;
  132.     /** year since 1900 */
  133.     apr_int32_t tm_year;
  134.     /** (0-6) days since sunday */
  135.     apr_int32_t tm_wday;
  136.     /** (0-365) days since jan 1 */
  137.     apr_int32_t tm_yday;
  138.     /** daylight saving time */
  139.     apr_int32_t tm_isdst;
  140.     /** seconds east of UTC */
  141.     apr_int32_t tm_gmtoff;
  142. };
  143.  
  144. /**
  145.  * convert an ansi time_t to an apr_time_t
  146.  * @param result the resulting apr_time_t
  147.  * @param input the time_t to convert
  148.  */
  149. APR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result, 
  150.                                                     time_t input);
  151.  
  152. /**
  153.  * convert a time to its human readable components using an offset
  154.  * from GMT
  155.  * @param result the exploded time
  156.  * @param input the time to explode
  157.  * @param offs the number of seconds offset to apply
  158.  * @param zone the zone description
  159.  */
  160. APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result,
  161.                                           apr_time_t input,
  162.                                           apr_int32_t offs);
  163.  
  164. /** @deprecated @see apr_time_exp_tz */
  165. APR_DECLARE(apr_status_t) apr_explode_time(apr_time_exp_t *result,
  166.                                            apr_time_t input,
  167.                                            apr_int32_t offs);
  168.  
  169. /**
  170.  * convert a time to its human readable components in GMT timezone
  171.  * @param result the exploded time
  172.  * @param input the time to explode
  173.  */
  174. APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, 
  175.                                            apr_time_t input);
  176.  
  177. /**
  178.  * convert a time to its human readable components in local timezone
  179.  * @param result the exploded time
  180.  * @param input the time to explode
  181.  */
  182. APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, 
  183.                                           apr_time_t input);
  184.  
  185. /** @deprecated @see apr_time_exp_lt */
  186. APR_DECLARE(apr_status_t) apr_explode_localtime(apr_time_exp_t *result, 
  187.                                                 apr_time_t input);
  188.  
  189. /**
  190.  * Convert time value from human readable format to a numeric apr_time_t 
  191.  * e.g. elapsed usec since epoch
  192.  * @param result the resulting imploded time
  193.  * @param input the input exploded time
  194.  */
  195. APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, 
  196.                                            apr_time_exp_t *input);
  197.  
  198. /**
  199.  * Convert time value from human readable format to a numeric apr_time_t that
  200.  * always represents GMT
  201.  * @param result the resulting imploded time
  202.  * @param input the input exploded time
  203.  */
  204. APR_DECLARE(apr_status_t) apr_implode_gmt(apr_time_t *result, 
  205.                                           apr_time_exp_t *input);
  206.  
  207. /**
  208.  * Sleep for the specified number of micro-seconds.
  209.  * @param t desired amount of time to sleep.
  210.  * @warning May sleep for longer than the specified time. 
  211.  */
  212. APR_DECLARE(void) apr_sleep(apr_interval_time_t t);
  213.  
  214. /** length of a RFC822 Date */
  215. #define APR_RFC822_DATE_LEN (30)
  216. /**
  217.  * apr_rfc822_date formats dates in the RFC822
  218.  * format in an efficient manner.  it is a fixed length
  219.  * format and requires the indicated amount of storage
  220.  * including trailing \0
  221.  * @param date_str String to write to.
  222.  * @param t the time to convert 
  223.  */
  224. APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t);
  225.  
  226. /** length of a CTIME date */
  227. #define APR_CTIME_LEN (25)
  228. /**
  229.  * apr_ctime formats dates in the ctime() format
  230.  * in an efficient manner.  it is a fixed length format
  231.  * and requires the indicated amount of storage
  232.  * Unlike ANSI/ISO C ctime(), apr_ctime() does not include
  233.  * a \n at the end of the string.
  234.  * including trailing \0 
  235.  * @param date_str String to write to.
  236.  * @param t the time to convert 
  237.  */
  238. APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t);
  239.  
  240. /**
  241.  * formats the exploded time according to the format specified
  242.  * @param s string to write to
  243.  * @param retsize The length of the returned string
  244.  * @param max The maximum length of the string
  245.  * @param format The format for the time string
  246.  * @param tm The time to convert
  247.  */
  248. APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, 
  249.                                        apr_size_t max, const char *format, 
  250.                                        apr_time_exp_t *tm);
  251.  
  252. #ifdef __cplusplus
  253. }
  254. #endif
  255.  
  256. #endif  /* ! APR_TIME_H */
  257.